io-ts

What is io-ts?

The io-ts npm package is a TypeScript library that allows for the definition of runtime types, and the automatic validation of runtime values against those types. It leverages TypeScript's type system to ensure that data structures conform to specified schemas, providing a bridge between the runtime data and compile-time types.

What are io-ts's main functionalities?

Runtime type validation

This feature allows you to define a type and then validate an object against that type at runtime. If the object matches the type, the 'Right' branch is executed; otherwise, the 'Left' branch indicates a validation error.

{"const t = require('io-ts');\nconst User = t.type({\n  name: t.string,\n  age: t.number\n});\nconst result = User.decode({ name: 'Alice', age: 25 });\nif (result._tag === 'Right') {\n  console.log('Valid!', result.right);\n} else {\n  console.log('Invalid!', result.left);\n}"}

Type composition

io-ts allows for the composition of types, enabling complex type definitions by combining simpler ones. This is useful for building up the shape of data structures from reusable type components.

{"const t = require('io-ts');\nconst Name = t.string;\nconst Age = t.number;\nconst User = t.type({ name: Name, age: Age });\nconst result = User.decode({ name: 'Bob', age: 'not-a-number' });\n// result will be an instance of Left since 'age' is not a number"}

Custom types

io-ts allows the creation of custom types with additional validation logic. In this example, a 'PositiveNumber' type is created that only accepts positive numbers.

{"const t = require('io-ts');\nconst PositiveNumber = t.brand(\n  t.number,\n  (n): n is t.Branded<number, { readonly PositiveNumber: unique symbol }> => n > 0,\n  'PositiveNumber'\n);\nconst result = PositiveNumber.decode(-5);\n// result will be an instance of Left since the number is not positive"}

Other packages similar to io-ts

ajv

Ajv is a JSON schema validator that provides runtime data validation using predefined JSON schemas. It is similar to io-ts in that it validates data structures at runtime, but it uses JSON schema as the basis for validation rather than TypeScript types.

joi

Joi is an object schema validation library that allows for the description and validation of JavaScript objects. It is similar to io-ts in providing runtime validation, but it uses a fluent API for schema definition and does not integrate with TypeScript types in the same way.

yup

Yup is a JavaScript schema builder for value parsing and validation. It defines a schema using a declarative API and validates objects against the schema. Like io-ts, it provides runtime validation, but it does not leverage TypeScript's type system for type definitions.

class-validator

Class-validator allows for validation of class instances based on decorators. It is similar to io-ts in that it provides runtime validation, but it is designed to work with classes and decorators, offering a different approach to defining validation rules.

README

• Installation
• Usage
  • Stable features
  • Experimental features (version 2.2+)

Installation

To install the stable version

npm i io-ts fp-ts

Note. fp-ts is a peer dependency for io-ts

Usage

Stable features

• Documentation of the main stable features (index.ts module)

Experimental modules (version 2.2+)

Experimental modules (*) are published in order to get early feedback from the community, see these tracking issues for further discussions and enhancements.

The experimental modules are independent and backward-incompatible with stable ones.

• Decoder.ts module
• Encoder.ts module
• Codec.ts module
• Eq.ts module
• Schema.ts module (advanced feature)

(*) A feature tagged as Experimental is in a high state of flux, you're at risk of it changing without notice.

Changelog

2.2.21

• Bug Fix
  • Handle record keys outside domain, #705 (@tgfisher4)